home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 176-200 / scopedisk199 / experimentiv / experiment.doc < prev    next >
Text File  |  1995-03-19  |  13KB  |  301 lines
  1. Experiment IV, Revision 1.8.
  2. ---------------------
  3.  
  4. Legalese
  5. --------
  6.  
  7. This program is copyright 1991, Marc Espie.
  8.  
  9. It is freely distributable, for non-commercial purpose only, provided
  10. that the program and this file stay together.
  11.  
  12. THIS PROGRAM IS PROVIDED ``AS IS'' WITHOUT WARRANTY OF ANY KIND,
  13. EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
  14. THE IMPLIED WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE
  15. RISK AS TO THE RESULTS, RELIABILITY AND PERFORMANCE OF THIS PROGRAM IS
  16. ASSUMED BY YOU.
  17.  
  18. THIS DISCLAIMER SHALL SUPERCEDE ANY VERBAL OR WRITTEN STATEMENT TO THE
  19. CONTRARY.
  20.  
  21. Ok, now I've covered myself. Let's go for some explanations.
  22.  
  23. I want to keep some control over this program right now, because I'm
  24. still working on it.  ``Commercial purposes'' include inclusion in a
  25. so-called ``PD software library'' at a prohibitive cost, like more
  26. than $5 by disk.  I would appreciate it if you would contact me before
  27. including it in any library, because I may have a newer version
  28. ready at that point.
  29.  
  30. Experiment IV is a small (<40K) soundtracker music player.  As such, it
  31. understands a reasonable subset of the various SoundTracker/ProTracker/
  32. NoiseTracker/... commands, that is, it is able to play about every
  33. module correctly... each of my collection of 156 modules plays correctly.
  34.  
  35. Support for MED, SMUS, FutureComposer... has not been added yet, nor for
  36. packed modules.
  37.  
  38. It is system-friendly:  uses a minimal amount of chip memory, returns
  39. all resources to the system, aborts gracefully when there is a problem,
  40. asks for the audio.device, asks for the interrupts, and gives everything
  41. back gracefully. It also does cooperate with other programs for use of
  42. the audio.device, which means that your terminal should still be able to
  43. beep gracefully... unless that terminal doesn't cooperate with other
  44. programs of course.
  45.  
  46. Since it uses the CIAB timer, it should not depend on being run on a PAL
  47. or NTSC amiga.
  48.  
  49. Under normal conditions, it is fast enough to be used with a terminal
  50. emulator program. It runs almost indifferently on any amiga, though it
  51. won't be of much use without some memory: with less than one megabyte,
  52. using it with another program will be something of a challenge.
  53. (``Almost indifferently'', because it recognizes 2.0 and adds some bonus
  54. features on 2.0 systems.)
  55.  
  56. Report serious bugs to espie@flamingo.stanford.edu, and watch out for
  57. a newer version.
  58.  
  59. Installation:
  60. ------------
  61.  
  62. This program doesn't really NEED any installation.  However, it really
  63. cries for the arp.library to be fully functional.
  64.  
  65. The program knows that music: is a good place to search for modules, so
  66. if all your modules are at the same place, assign Music: to that place.
  67.  
  68. You can also put it in your startup-sequence or WBStartup (there is a
  69. DONOTWAIT tooltype in the icon).
  70.  
  71. Use and features:
  72. ----------------
  73.  
  74. You can start Experiment_IV either from CLI or Workbench.  It does
  75. detach itself from the CLI. From the CLI, you can give full module names
  76. on startup, it will load the first module and start playing. If the
  77. arp.library is installed, it does pattern matching.  From the workbench,
  78. you can shift click on several module icons, likewise.
  79.  
  80. If you don't give any name, it will just wait for you to load anything...
  81. which will be a trifle difficult if you are under 1.3 and the arp library
  82. is not available.
  83.  
  84. There are some configuration options, that you specify as tooltypes in
  85. the icon, or give on the command line.
  86.  
  87. X=x             : starting X position of the window. Won't open if
  88.                   somewhat over 500.
  89. Y=y             : starting Y position of the window.
  90. VOLUME=p        : p% of maximal volume.
  91. PRIORITY=p      : audio channel priority, for arbitration with other tasks.
  92. START=k         : starts the first song at pattern k.
  93. REPEAT=n        : repeats each song n times.  Default is indefinitely.
  94. DONOTWAIT       : set that for WBStartup use.
  95. TRANSPOSE=t     : transpose the song t halftones.
  96. SPEED=NTSC
  97.    or SPEED=PAL : starting speed (default is PAL).
  98.  
  99. Transpose is a funny option, not intended to be useful, since it does no
  100. range checking... use at your own risk.
  101.  
  102. One of my favorite startups is "exp repeat=1 volume=75 music:#?/#?"
  103.  
  104. ...after you've specified a file or pattern, you have a small window
  105. opened and (hopefully) some music running.  If no music is playing,
  106. check your audio output, then check that no other program has allocated
  107. the audio.device but doesn't use it (example: MED, JRComm (sigh...)).
  108. There is a status line, with the name of the current module and useful
  109. indications (current pattern:length of song).
  110.  
  111. There are five little gadgets at the bottom of that window.
  112.  
  113. - Load.  Gets to the next module (if several are specified on start)
  114. then asks for a module name (needs the file requester, see installation),
  115. loads it and plays it. This is ``seamless'' play, if it is possible to
  116. store the two modules in memory at the same time.  Otherwise, the first
  117. module will stop, the second module will hopefully fit in memory, and
  118. play will resume. (In really tight memory conditions, the file requester
  119. might refuse to appear...)
  120.  
  121. - Restart.  Restart the module at the beginning, useful when the speed
  122. is wrong.  Also used to restart a module which has replayed N times.
  123.  
  124. - Pause:  one click to pause, another to continue.  Sometimes, the
  125. program isn't playing, and the pause is not on. Either you have no
  126. module running, or something else is using the audio.device.
  127.  
  128. - PAL.  A speed.  You can cycle through Slow/PAL/NTSC/Fast/Scan.
  129. PAL and NTSC are the type of the machine that module was composed on,
  130. slow and fast are... well... slow and fast.
  131. Scan is very fast, a bit noisy, but useful to get somewhere quickly.
  132.  
  133. - Std.  This is a ``compatibility'' gadget.  Different trackers have
  134. different interpretations of the speed commands...  I found three
  135. different ones.  The standard one should be able to play most modules,
  136. just toggle and restart for modules which don't play right.  If you
  137. don't get it to run with any setting, drop me a note...(sigh...)
  138.  
  139. - Close gadget:  stops player and quits.  Warning: no safecheck, if you
  140. close it, you've done it.
  141.  
  142. There is some Workbench support:  you can start the player with a set of
  143. modules (shift-click), or even use it as the default tool for modules.
  144. In that case, the load gadget will first walk through all these startup
  145. modules, before bringing up the file requester.
  146.  
  147.  
  148. Version number:
  149. --------------
  150. Whenever the program window is active (just click on the title bar),
  151. the screen title bar displays some information about the program, like
  152. the version and the compilation date.
  153.  
  154. How to regain memory:
  155. --------------------
  156. If you try to close the window while a song is loaded, it will first
  157. unload the song and give you some memory back. You'll have to depress
  158. close again to actually exit.
  159.  
  160. Customizing modules:
  161. -------------------
  162. It's a good idea to add icons to your modules. They should be projects
  163. with Experiment_IV as the default tool. You can add some tooltypes to
  164. these, like SPEED=NTSC, MODE=STD, MODE=OLD, or MODE=NEW.  These will
  165. be recognized from workbench or CLI.
  166.  
  167. Albums:
  168. ------
  169. You can program whole albums of songs. Just create a file with a text
  170. editor with some filenames in it (one filename per line, no spaces
  171. before the filename).  Put an icon to that file, and add an ALBUM
  172. tooltype to it. That's it!  Paths of the filenames are relative to the
  173. album's directory.  You can also put patterns, or even other albums
  174. (be careful: recursion is NOT detected).
  175.  
  176. 2.0 specific support:
  177. --------------------
  178. I don't really support the 2.0 file requester nor extended dos library
  179. right now, but that should come. However, the program opens an
  180. appwindow.  This means that you can also load songs and albums by just
  181. dragging icons into the program window...
  182.  
  183. Nice things:
  184. -----------
  185. If you make a mistake and ask it to load a non-module file, the program
  186. will most often not be fooled, and just do nothing about it.
  187.  
  188. The pause feature can be used with several players. If you fire up
  189. several players at different priorities (option *), the highest priority
  190. one will play, unless you pause it, in which case the next one will go.
  191. This is very useful for comparing different versions of the same module.
  192. Non-confusion option:  the song-title display should change colors
  193. according to whether or not that player is running.
  194.  
  195. The program tries very hard not to fragment chip memory, and usually
  196. succeeds.  It just uses the exact amount of chip-memory needed for the
  197. samples, besides that needed for the file requester.
  198.  
  199. The program knows about preference fonts, and has a reasonable look
  200. under 2.0.
  201.  
  202. Not so nice things:
  203. ------------------
  204. There is no error report if something goes wrong, it just exits...
  205.  
  206. There is no check when you hit close by mistake.
  207.  
  208. The chip memory is allocated as a big chunk. If your memory is
  209. fragmented, you won't be able to load anything.
  210.  
  211. When the filerequester is up, the program can not listen to every event:
  212. the pattern counter doesn't get updated, another program asking for the
  213. audio.device will wait till you exit from the requester.
  214.  
  215. The volume control isn't user-friendly, and the player is able to do
  216. lots of things that aren't accessible to the user yet.
  217.  
  218. The way options are taken from various icons isn't always intuitive.
  219.  
  220. Known problems:
  221. --------------
  222. The player doesn't handle commands 5-9, and not all forms of the
  223. extended command (14) exist. ``Finetune'' is a theoretical possibility,
  224. not tested in practice. Some range-checks aren't done, the extended
  225. speed change (CIA control) is not thoroughly tested and can conflict
  226. with real old modules.
  227.  
  228. Some rare non-modules files might get played.  The result is a lots of
  229. noise, but harmless and bug-free (should be).
  230.  
  231. As with every other players, there are ``pops'' for some sound-changes.
  232. Correcting that will be difficult.
  233.  
  234. Under 2.02, the AmigaDOS file requester loses memory when you ask for
  235. events (or I've got something wrong...), so the arp file requester is
  236. used exclusively.
  237.  
  238. Under 1.3, the tooltypes aren't as flexible. The albums won't be
  239. recognized with just ALBUM, you need to enter something like
  240. ALBUM=kludge to get it to work.
  241.  
  242. The ``n repeat'' command is simple-minded, it will get confused by
  243. modules with lots of GOTOs.
  244.  
  245. The audio.device seems to have problems handling clients waiting for
  246. a locked channel.
  247.  
  248. Apparently, ADCMD_LOCK can freeze the ADCMD_ALLOCATE commands as
  249. intended, but also AbortIOs of these commands, until there is a change
  250. in the allocated channels. So closing a player waiting for channels
  251. might just hang until another player frees the channels.
  252.  
  253. Things to do (rough priority order, *=done)
  254. -----------------------------------
  255. * cleanup the event handling
  256. * release the source code.
  257.  
  258. * full workbench support (including 2.0 appwindow/appicon).
  259. - add support for MED, recognizes soundtracker variants.
  260. - powerpacker support.
  261. - preprocessing of modules to be able to jump anywhere without problems.
  262. - instruments library.
  263.  
  264. Compiling:
  265. ---------
  266. The sources to the program are in a different archive.
  267.  
  268. If you want to recompile the program, there should be no problems...
  269. If you have only 1.3, you will have to make some changes to accomodate
  270. all the structures not defined in 1.3 (just giving a dummy definition
  271. or commenting out part of the code is enough.).  Besides that, this is
  272. pretty much standard ANSI C and AMIGA OS code.
  273.  
  274. Also, interrupt.c uses the ASM keyword of Lattice. Replacing the C call
  275. by an assembly language stub is a two-minute job.
  276. It also needs some support for far absolute addresses. If you don't
  277. have it, you will have to modify audio_hard.c and interrupt.c (note
  278. that you can't have any absolute references to ``task-owned''
  279. variables in audio_hard.c.
  280.  
  281. You will need to disable stack-checking for the interrupt routine
  282. modules (all modules flagged with -v in the lattice makefile.
  283.  
  284. Some local peculiarities of my system: the arp includes are installed,
  285. and I've got a directory ``custom'' where I stuff some includes
  286. (cleanup.h for this project).  Cleanup is an ``auto cleanup module''.
  287. If you want to modify my program, you had better understand how it works
  288. (see cleanup.h).  Basically, it enables me to keep track of everything I
  289. allocate. It's also very powerful for dynamic backtracking (check the
  290. heavy use of it in files.c).
  291.  
  292. The missing ``mymain.c'' is actually the lattice umain.c. It just
  293. does handle standard startup, and usually opens a console window
  294. on workbench (but I don't want that !). If you don't have Lattice,
  295. check your compiler for a suitable startup option.
  296.  
  297.  
  298.     Marc Espie (espie@flamingo.stanford.edu / espie@dmi.ens.fr
  299.                /espie@FRULM63)
  300.     5/20/91, Palo Alto.
  301.